SGI Freeware 1999 August

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_cvs.idb / usr / freeware / info / cvs.info-2.z / cvs.info-2

Wrap

GNU Info File | 1999-04-16 | 48.9 KB | 1,151 lines

This is Info file cvs.info, produced by Makeinfo version 1.67 from the input file ./cvs.texinfo. START-INFO-DIR-ENTRY * CVS: (cvs). Concurrent Versions System END-INFO-DIR-ENTRY Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. File: cvs.info, Node: Backing up, Next: Moving a repository, Prev: Creating a repository, Up: Repository Backing up a repository ======================= There is nothing particularly magical about the files in the repository; for the most part it is possible to back them up just like any other files. However, there are a few issues to consider. The first is that to be paranoid, one should either not use CVS during the backup, or have the backup program lock CVS while doing the backup. To not use CVS, you might forbid logins to machines which can access the repository, turn off your CVS server, or similar mechanisms. The details would depend on your operating system and how you have CVS set up. To lock CVS, you would create `#cvs.rfl' locks in each repository directory. See *Note Concurrency::, for more on CVS locks. Having said all this, if you just back up without any of these precautions, the results are unlikely to be particularly dire. Restoring from backup, the repository might be in an inconsistent state, but this would not be particularly hard to fix manually. When you restore a repository from backup, assuming that changes in the repository were made after the time of the backup, working directories which were not affected by the failure may refer to revisions which no longer exist in the repository. Trying to run CVS in such directories will typically produce an error message. One way to get those changes back into the repository is as follows: * Get a new working directory. * Copy the files from the working directory from before the failure over to the new working directory (do not copy the contents of the `CVS' directories, of course). * Working in the new working directory, use commands such as `cvs update' and `cvs diff' to figure out what has changed, and then when you are ready, commit the changes into the repository. File: cvs.info, Node: Moving a repository, Next: Remote repositories, Prev: Backing up, Up: Repository Moving a repository =================== Just as backing up the files in the repository is pretty much like backing up any other files, if you need to move a repository from one place to another it is also pretty much like just moving any other collection of files. The main thing to consider is that working directories point to the repository. The simplest way to deal with a moved repository is to just get a fresh working directory after the move. Of course, you'll want to make sure that the old working directory had been checked in before the move, or you figured out some other way to make sure that you don't lose any changes. If you really do want to reuse the existing working directory, it should be possible with manual surgery on the `CVS/Repository' files. You can see *Note Working directory storage::, for information on the `CVS/Repository' and `CVS/Root' files, but unless you are sure you want to bother, it probably isn't worth it. File: cvs.info, Node: Remote repositories, Next: Read-only access, Prev: Moving a repository, Up: Repository Remote repositories =================== Your working copy of the sources can be on a different machine than the repository. Using CVS in this manner is known as "client/server" operation. You run CVS on a machine which can mount your working directory, known as the "client", and tell it to communicate to a machine which can mount the repository, known as the "server". Generally, using a remote repository is just like using a local one, except that the format of the repository name is: :METHOD:USER@HOSTNAME:/path/to/repository The details of exactly what needs to be set up depend on how you are connecting to the server. If METHOD is not specified, and the repository name contains `:', then the default is `ext' or `server', depending on your platform; both are described in *Note Connecting via rsh::. * Menu: * Server requirements:: Memory and other resources for servers * Connecting via rsh:: Using the `rsh' program to connect * Password authenticated:: Direct connections using passwords * GSSAPI authenticated:: Direct connections using GSSAPI * Kerberos authenticated:: Direct connections with kerberos File: cvs.info, Node: Server requirements, Next: Connecting via rsh, Up: Remote repositories Server requirements ------------------- The quick answer to what sort of machine is suitable as a server is that requirements are modest--a server with 32M of memory or even less can handle a fairly large source tree with a fair amount of activity. The real answer, of course, is more complicated. Estimating the known areas of large memory consumption should be sufficient to estimate memory requirements. There are two such areas documented here; other memory consumption should be small by comparison (if you find that is not the case, let us know, as described in *Note BUGS::, so we can update this documentation). The first area of big memory consumption is large checkouts, when using the CVS server. The server consists of two processes for each client that it is serving. Memory consumption on the child process should remain fairly small. Memory consumption on the parent process, particularly if the network connection to the client is slow, can be expected to grow to slightly more than the size of the sources in a single directory, or two megabytes, whichever is larger. Multiplying the size of each CVS server by the number of servers which you expect to have active at one time should give an idea of memory requirements for the server. For the most part, the memory consumed by the parent process probably can be swap space rather than physical memory. The second area of large memory consumption is `diff', when checking in large files. This is required even for binary files. The rule of thumb is to allow about ten times the size of the largest file you will want to check in, although five times may be adequate. For example, if you want to check in a file which is 10 megabytes, you should have 100 megabytes of memory on the machine doing the checkin (the server machine for client/server, or the machine running CVS for non-client/server). This can be swap space rather than physical memory. Because the memory is only required briefly, there is no particular need to allow memory for more than one such checkin at a time. Resource consumption for the client is even more modest--any machine with enough capacity to run the operating system in question should have little trouble. For information on disk space requirements, see *Note Creating a repository::. File: cvs.info, Node: Connecting via rsh, Next: Password authenticated, Prev: Server requirements, Up: Remote repositories Connecting with rsh ------------------- CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user. For example, suppose you are the user `mozart' on the local machine `toe.grunge.com', and the server machine is `chainsaw.yard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory: toe.grunge.com mozart Then test that `rsh' is working with rsh -l bach chainsaw.yard.com 'echo $PATH' Next you have to make sure that `rsh' will be able to find the server. Make sure that the path which `rsh' printed in the above example includes the directory containing a program named `cvs' which is the server. You need to set the path in `.bashrc', `.cshrc', etc., not `.login' or `.profile'. Alternately, you can set the environment variable `CVS_SERVER' on the client machine to the filename of the server you want to use, for example `/usr/local/bin/cvs-1.6'. There is no need to edit `inetd.conf' or start a CVS server daemon. There are two access methods that you use in CVSROOT for rsh. `:server:' specifies an internal rsh client, which is supported only by some CVS ports. `:ext:' specifies an external rsh program. By default this is `rsh' but you may set the `CVS_RSH' environment variable to invoke another program which can access the remote server (for example, `remsh' on HP-UX 9 because `rsh' is something different). It must be a program which can transmit data to and from the server without modifying it; for example the Windows NT `rsh' is not suitable since it by default translates between CRLF and LF. The OS/2 CVS port has a hack to pass `-b' to `rsh' to get around this, but since this could potentially cause problems for programs other than the standard `rsh', it may change in the future. If you set `CVS_RSH' to `SSH' or some other rsh replacement, the instructions in the rest of this section concerning `.rhosts' and so on are likely to be inapplicable; consult the documentation for your rsh replacement. Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.yard.com', you are ready to go: cvs -d :ext:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo (The `bach@' can be omitted if the username is the same on both the local and remote hosts.) File: cvs.info, Node: Password authenticated, Next: GSSAPI authenticated, Prev: Connecting via rsh, Up: Remote repositories Direct connection with password authentication ---------------------------------------------- The CVS client can also connect to the server using a password protocol. This is particularly useful if using `rsh' is not feasible (for example, the server is behind a firewall), and Kerberos also is not available. To use this method, it is necessary to make some adjustments on both the server and client sides. * Menu: * Password authentication server:: Setting up the server * Password authentication client:: Using the client * Password authentication security:: What this method does and does not do File: cvs.info, Node: Password authentication server, Next: Password authentication client, Up: Password authenticated Setting up the server for password authentication ................................................. First of all, you probably want to tighten the permissions on the `$CVSROOT' and `$CVSROOT/CVSROOT' directories. See *Note Password authentication security::, for more details. On the server side, the file `/etc/inetd.conf' needs to be edited so `inetd' knows to run the command `cvs pserver' when it receives a connection on the right port. By default, the port number is 2401; it would be different if your client were compiled with `CVS_AUTH_PORT' defined to something else, though. If your `inetd' allows raw port numbers in `/etc/inetd.conf', then the following (all on a single line in `inetd.conf') should be sufficient: 2401 stream tcp nowait root /usr/local/bin/cvs cvs --allow-root=/usr/cvsroot pserver You could also use the `-T' option to specify a temporary directory. The `--allow-root' option specifies the allowable CVSROOT directory. Clients which attempt to use a different CVSROOT directory will not be allowed to connect. If there is more than one CVSROOT directory which you want to allow, repeat the option. If your `inetd' wants a symbolic service name instead of a raw port number, then put this in `/etc/services': cvspserver 2401/tcp and put `cvspserver' instead of `2401' in `inetd.conf'. Once the above is taken care of, restart your `inetd', or do whatever is necessary to force it to reread its initialization files. Because the client stores and transmits passwords in cleartext (almost--see *Note Password authentication security::, for details), a separate CVS password file may be used, so people don't compromise their regular passwords when they access the repository. This file is `$CVSROOT/CVSROOT/passwd' (*note Intro administrative files::.). Its format is similar to `/etc/passwd', except that it only has two or three fields, username, password, and optional username for the server to use. For example: bach:ULtgRLXo7NRxs cwang:1sOp854gDF3DY The password is encrypted according to the standard Unix `crypt()' function, so it is possible to paste in passwords directly from regular Unix `passwd' files. When authenticating a password, the server first checks for the user in the CVS `passwd' file. If it finds the user, it compares against that password. If it does not find the user, or if the CVS `passwd' file does not exist, then the server tries to match the password using the system's user-lookup routine (using the system's user-lookup routine can be disabled by setting `SystemAuth=no' in the config file, *note config::.). When using the CVS `passwd' file, the server runs as the username specified in the third argument in the entry, or as the first argument if there is no third argument (in this way CVS allows imaginary usernames provided the CVS `passwd' file indicates corresponding valid system usernames). In any case, CVS will have no privileges which the (valid) user would not have. It is possible to "map" cvs-specific usernames onto system usernames (i.e., onto system login names) in the `$CVSROOT/CVSROOT/passwd' file by appending a colon and the system username after the password. For example: cvs:ULtgRLXo7NRxs:kfogel generic:1sOp854gDF3DY:spwang anyone:1sOp854gDF3DY:spwang Thus, someone remotely accessing the repository on `chainsaw.yard.com' with the following command: cvs -d :pserver:cvs@chainsaw.yard.com:/usr/local/cvsroot checkout foo would end up running the server under the system identity kfogel, assuming successful authentication. However, the remote user would not necessarily need to know kfogel's system password, as the `$CVSROOT/CVSROOT/passwd' file might contain a different password, used only for CVS. And as the example above indicates, it is permissible to map multiple cvs usernames onto a single system username. This feature is designed to allow people repository access without full system access (in particular, see *Note Read-only access::); however, also see *Note Password authentication security::. Any sort of repository access very likely implies a degree of general system access as well. Right now, the only way to put a password in the CVS `passwd' file is to paste it there from somewhere else. Someday, there may be a `cvs passwd' command. File: cvs.info, Node: Password authentication client, Next: Password authentication security, Prev: Password authentication server, Up: Password authenticated Using the client with password authentication ............................................. Before connecting to the server, the client must "log in" with the command `cvs login'. Logging in verifies a password with the server, and also records the password for later transactions with the server. The `cvs login' command needs to know the username, server hostname, and full repository path, and it gets this information from the repository argument or the `CVSROOT' environment variable. `cvs login' is interactive -- it prompts for a password: cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot login CVS password: The password is checked with the server; if it is correct, the `login' succeeds, else it fails, complaining that the password was incorrect. Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password: cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo The `:pserver:' is necessary because without it, CVS will assume it should use `rsh' to connect with the server (*note Connecting via rsh::.). (Once you have a working copy checked out and are running CVS commands from within it, there is no longer any need to specify the repository explicitly, because CVS records it in the working copy's `CVS' subdirectory.) Passwords are stored by default in the file `$HOME/.cvspass'. Its format is human-readable, but don't edit it unless you know what you are doing. The passwords are not stored in cleartext, but are trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file). The password for the currently choosen remote repository can be removed from the CVS_PASSFILE by using the `cvs logout' command. The `CVS_PASSFILE' environment variable overrides this default. If you use this variable, make sure you set it *before* `cvs login' is run. If you were to set it after running `cvs login', then later CVS commands would be unable to look up the password for transmission to the server. File: cvs.info, Node: Password authentication security, Prev: Password authentication client, Up: Password authenticated Security considerations with password authentication .................................................... The passwords are stored on the client side in a trivial encoding of the cleartext, and transmitted in the same encoding. The encoding is done only to prevent inadvertent password compromises (i.e., a system administrator accidentally looking at the file), and will not prevent even a naive attacker from gaining the password. The separate CVS password file (*note Password authentication server::.) allows people to use a different password for repository access than for login access. On the other hand, once a user has non-read-only access to the repository, she can execute programs on the server system through a variety of means. Thus, repository access implies fairly broad system access as well. It might be possible to modify CVS to prevent that, but no one has done so as of this writing. Furthermore, there may be other ways in which having access to CVS allows people to gain more general access to the system; no one has done a careful audit. Note that because the `$CVSROOT/CVSROOT' directory contains `passwd' and other files which are used to check security, you must control the permissions on this directory as tightly as the permissions on `/etc'. The same applies to the `$CVSROOT' directory itself and any directory above it in the tree. Anyone who has write access to such a directory will have the ability to become any user on the system. Note that these permissions are typically tighter than you would use if you are not using pserver. In summary, anyone who gets the password gets repository access, and some measure of general system access as well. The password is available to anyone who can sniff network packets or read a protected (i.e., user read-only) file. If you want real security, get Kerberos. File: cvs.info, Node: GSSAPI authenticated, Next: Kerberos authenticated, Prev: Password authenticated, Up: Remote repositories Direct connection with GSSAPI ----------------------------- GSSAPI is a generic interface to network security systems such as Kerberos 5. If you have a working GSSAPI library, you can have CVS connect via a direct TCP connection, authenticating with GSSAPI. To do this, CVS needs to be compiled with GSSAPI support; when configuring CVS it tries to detect whether GSSAPI libraries using kerberos version 5 are present. You can also use the `--with-gssapi' flag to configure. The connection is authenticated using GSSAPI, but the message stream is *not* authenticated by default. You must use the `-a' global option to request stream authentication. The data transmitted is *not* encrypted by default. Encryption support must be compiled into both the client and the server; use the `--enable-encrypt' configure option to turn it on. You must then use the `-x' global option to request encryption. GSSAPI connections are handled on the server side by the same server which handles the password authentication server; see *Note Password authentication server::. If you are using a GSSAPI mechanism such as Kerberos which provides for strong authentication, you will probably want to disable the ability to authenticate via cleartext passwords. To do so, create an empty `CVSROOT/passwd' password file, and set `SystemAuth=no' in the config file (*note config::.). The GSSAPI server uses a principal name of cvs/HOSTNAME, where HOSTNAME is the canonical name of the server host. You will have to set this up as required by your GSSAPI mechanism. To connect using GSSAPI, use `:gserver:'. For example, cvs -d :gserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo File: cvs.info, Node: Kerberos authenticated, Prev: GSSAPI authenticated, Up: Remote repositories Direct connection with kerberos ------------------------------- The easiest way to use kerberos is to use the kerberos `rsh', as described in *Note Connecting via rsh::. The main disadvantage of using rsh is that all the data needs to pass through additional programs, so it may be slower. So if you have kerberos installed you can connect via a direct TCP connection, authenticating with kerberos. This section concerns the kerberos network security system, version 4. Kerberos version 5 is supported via the GSSAPI generic network security interface, as described in the previous section. To do this, CVS needs to be compiled with kerberos support; when configuring CVS it tries to detect whether kerberos is present or you can use the `--with-krb4' flag to configure. The data transmitted is *not* encrypted by default. Encryption support must be compiled into both the client and server; use the `--enable-encryption' configure option to turn it on. You must then use the `-x' global option to request encryption. You need to edit `inetd.conf' on the server machine to run `cvs kserver'. The client uses port 1999 by default; if you want to use another port specify it in the `CVS_CLIENT_PORT' environment variable on the client. When you want to use CVS, get a ticket in the usual way (generally `kinit'); it must be a ticket which allows you to log into the server machine. Then you are ready to go: cvs -d :kserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo Previous versions of CVS would fall back to a connection via rsh; this version will not do so. File: cvs.info, Node: Read-only access, Next: Server temporary directory, Prev: Remote repositories, Up: Repository Read-only repository access =========================== It is possible to grant read-only repository access to people using the password-authenticated server (*note Password authenticated::.). (The other access methods do not have explicit support for read-only users because those methods all assume login access to the repository machine anyway, and therefore the user can do whatever local file permissions allow her to do.) A user who has read-only access can do only those CVS operations which do not modify the repository, except for certain "administrative" files (such as lock files and the history file). It may be desirable to use this feature in conjunction with user-aliasing (*note Password authentication server::.). Unlike with previous versions of CVS, read-only users should be able merely to read the repository, and not to execute programs on the server or otherwise gain unexpected levels of access. Or to be more accurate, the *known* holes have been plugged. Because this feature is new and has not received a comprehensive security audit, you should use whatever level of caution seems warranted given your attitude concerning security. There are two ways to specify read-only access for a user: by inclusion, and by exclusion. "Inclusion" means listing that user specifically in the `$CVSROOT/CVSROOT/readers' file, which is simply a newline-separated list of users. Here is a sample `readers' file: melissa splotnik jrandom (Don't forget the newline after the last user.) "Exclusion" means explicitly listing everyone who has *write* access--if the file $CVSROOT/CVSROOT/writers exists, then only those users listed in it have write access, and everyone else has read-only access (of course, even the read-only users still need to be listed in the CVS `passwd' file). The `writers' file has the same format as the `readers' file. Note: if your CVS `passwd' file maps cvs users onto system users (*note Password authentication server::.), make sure you deny or grant read-only access using the *cvs* usernames, not the system usernames. That is, the `readers' and `writers' files contain cvs usernames, which may or may not be the same as system usernames. Here is a complete description of the server's behavior in deciding whether to grant read-only or read-write access: If `readers' exists, and this user is listed in it, then she gets read-only access. Or if `writers' exists, and this user is NOT listed in it, then she also gets read-only access (this is true even if `readers' exists but she is not listed there). Otherwise, she gets full read-write access. Of course there is a conflict if the user is listed in both files. This is resolved in the more conservative way, it being better to protect the repository too much than too little: such a user gets read-only access. File: cvs.info, Node: Server temporary directory, Prev: Read-only access, Up: Repository Temporary directories for the server ==================================== While running, the CVS server creates temporary directories. They are named cvs-servPID where PID is the process identification number of the server. They are located in the directory specified by the `TMPDIR' environment variable (*note Environment variables::.), the `-T' global option (*note Global options::.), or failing that `/tmp'. In most cases the server will remove the temporary directory when it is done, whether it finishes normally or abnormally. However, there are a few cases in which the server does not or cannot remove the temporary directory, for example: * If the server aborts due to an internal server error, it may preserve the directory to aid in debugging * If the server is killed in a way that it has no way of cleaning up (most notably, `kill -KILL' on unix). * If the system shuts down without an orderly shutdown, which tells the server to clean up. In cases such as this, you will need to manually remove the `cvs-servPID' directories. As long as there is no server running with process identification number PID, it is safe to do so. File: cvs.info, Node: Starting a new project, Next: Revisions, Prev: Repository, Up: Top Starting a project with CVS *************************** Because renaming files and moving them between directories is somewhat inconvenient, the first thing you do when you start a new project should be to think through your file organization. It is not impossible to rename or move files, but it does increase the potential for confusion and CVS does have some quirks particularly in the area of renaming directories. *Note Moving files::. What to do next depends on the situation at hand. * Menu: * Setting up the files:: Getting the files into the repository * Defining the module:: How to make a module of the files File: cvs.info, Node: Setting up the files, Next: Defining the module, Up: Starting a new project Setting up the files ==================== The first step is to create the files inside the repository. This can be done in a couple of different ways. * Menu: * From files:: This method is useful with old projects where files already exists. * From other version control systems:: Old projects where you want to preserve history from another system. * From scratch:: Creating a directory tree from scratch. File: cvs.info, Node: From files, Next: From other version control systems, Up: Setting up the files Creating a directory tree from a number of files ------------------------------------------------ When you begin using CVS, you will probably already have several projects that can be put under CVS control. In these cases the easiest way is to use the `import' command. An example is probably the easiest way to explain how to use it. If the files you want to install in CVS reside in `WDIR', and you want them to appear in the repository as `$CVSROOT/yoyodyne/RDIR', you can do this: $ cd WDIR $ cvs import -m "Imported sources" yoyodyne/RDIR yoyo start Unless you supply a log message with the `-m' flag, CVS starts an editor and prompts for a message. The string `yoyo' is a "vendor tag", and `start' is a "release tag". They may fill no purpose in this context, but since CVS requires them they must be present. *Note Tracking sources::, for more information about them. You can now verify that it worked, and remove your original source directory. $ cd .. $ mv DIR DIR.orig $ cvs checkout yoyodyne/DIR # Explanation below $ diff -r DIR.orig yoyodyne/DIR $ rm -r DIR.orig Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in DIR, bypassing CVS. Of course, it would be wise to make sure that you have a backup of the sources before you remove them. The `checkout' command can either take a module name as argument (as it has done in all previous examples) or a path name relative to `$CVSROOT', as it did in the example above. It is a good idea to check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable, and that they belong to the proper groups. *Note File permissions::. If some of the files you want to import are binary, you may want to use the wrappers features to specify which files are binary and which are not. *Note Wrappers::. File: cvs.info, Node: From other version control systems, Next: From scratch, Prev: From files, Up: Setting up the files Creating Files From Other Version Control Systems ------------------------------------------------- If you have a project which you are maintaining with another version control system, such as RCS, you may wish to put the files from that project into CVS, and preserve the revision history of the files. From RCS If you have been using RCS, find the RCS files--usually a file named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it could be other places; consult the RCS documentation for details). Then create the appropriate directories in CVS if they do not already exist. Then copy the files into the appropriate directories in the CVS repository (the name in the repository must be the name of the source file with `,v' added; the files go directly in the appopriate directory of the repository, not in an `RCS' subdirectory). This is one of the few times when it is a good idea to access the CVS repository directly, rather than using CVS commands. Then you are ready to check out a new working directory. The RCS file should not be locked when you move it into CVS; if it is, CVS will have trouble letting you operate on it. From another version control system Many version control systems have the ability to export RCS files in the standard format. If yours does, export the RCS files and then follow the above instructions. Failing that, probably your best bet is to write a script that will check out the files one revision at a time using the command line interface to the other system, and then check the revisions into CVS. The `sccs2rcs' script mentioned below may be a useful example to follow. From SCCS There is a script in the `contrib' directory of the CVS source distribution called `sccs2rcs' which converts SCCS files to RCS files. Note: you must run it on a machine which has both SCCS and RCS installed, and like everything else in contrib it is unsupported (your mileage may vary). From PVCS There is a script in the `contrib' directory of the CVS source distribution called `pvcs_to_rcs' which converts PVCS archives to RCS files. You must run it on a machine which has both PVCS and RCS installed, and like everything else in contrib it is unsupported (your mileage may vary). See the comments in the script for details. File: cvs.info, Node: From scratch, Prev: From other version control systems, Up: Setting up the files Creating a directory tree from scratch -------------------------------------- For a new project, the easiest thing to do is probably to create an empty directory structure, like this: $ mkdir tc $ mkdir tc/man $ mkdir tc/testing After that, you use the `import' command to create the corresponding (empty) directory structure inside the repository: $ cd tc $ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start Then, use `add' to add files (and new directories) as they appear. Check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable. File: cvs.info, Node: Defining the module, Prev: Setting up the files, Up: Starting a new project Defining the module =================== The next step is to define the module in the `modules' file. This is not strictly necessary, but modules can be convenient in grouping together related files and directories. In simple cases these steps are sufficient to define a module. 1. Get a working copy of the modules file. $ cvs checkout CVSROOT/modules $ cd CVSROOT 2. Edit the file and insert a line that defines the module. *Note Intro administrative files::, for an introduction. *Note modules::, for a full description of the modules file. You can use the following line to define the module `tc': tc yoyodyne/tc 3. Commit your changes to the modules file. $ cvs commit -m "Added the tc module." modules 4. Release the modules module. $ cd .. $ cvs release -d CVSROOT File: cvs.info, Node: Revisions, Next: Branching and merging, Prev: Starting a new project, Up: Top Revisions ********* For many uses of CVS, one doesn't need to worry too much about revision numbers; CVS assigns numbers such as `1.1', `1.2', and so on, and that is all one needs to know. However, some people prefer to have more knowledge and control concerning how CVS assigns revision numbers. If one wants to keep track of a set of revisions involving more than one file, such as which revisions went into a particular release, one uses a "tag", which is a symbolic revision which can be assigned to a numeric revision in each file. * Menu: * Revision numbers:: The meaning of a revision number * Versions revisions releases:: Terminology used in this manual * Assigning revisions:: Assigning revisions * Tags:: Tags-Symbolic revisions * Sticky tags:: Certain tags are persistent File: cvs.info, Node: Revision numbers, Next: Versions revisions releases, Up: Revisions Revision numbers ================ Each version of a file has a unique "revision number". Revision numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A revision number always has an even number of period-separated decimal integers. By default revision 1.1 is the first revision of a file. Each successive revision is given a new number by increasing the rightmost number by one. The following figure displays a few revisions, with newer revisions to the right. +-----+ +-----+ +-----+ +-----+ +-----+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! +-----+ +-----+ +-----+ +-----+ +-----+ It is also possible to end up with numbers containing more than one period, for example `1.3.2.2'. Such revisions represent revisions on branches (*note Branching and merging::.); such revision numbers are explained in detail in *Note Branches and revisions::. File: cvs.info, Node: Versions revisions releases, Next: Assigning revisions, Prev: Revision numbers, Up: Revisions Versions, revisions and releases ================================ A file can have several versions, as described above. Likewise, a software product can have several versions. A software product is often given a version number such as `4.1.1'. Versions in the first sense are called "revisions" in this document, and versions in the second sense are called "releases". To avoid confusion, the word "version" is almost never used in this document. File: cvs.info, Node: Assigning revisions, Next: Tags, Prev: Versions revisions releases, Up: Revisions Assigning revisions =================== By default, CVS will assign numeric revisions by leaving the first number the same and incrementing the second number. For example, `1.1', `1.2', `1.3', etc. When adding a new file, the second number will always be one and the first number will equal the highest first number of any file in that directory. For example, the current directory contains files whose highest numbered revisions are `1.7', `3.1', and `4.12', then an added file will be given the numeric revision `4.1'. Normally there is no reason to care about the revision numbers--it is easier to treat them as internal numbers that CVS maintains, and tags provide a better way to distinguish between things like release 1 versus release 2 of your product (*note Tags::.). However, if you want to set the numeric revisions, the `-r' option to `cvs commit' can do that. The `-r' option implies the `-f' option, in the sense that it causes the files to be committed even if they are not modified. For example, to bring all your files up to revision 3.0 (including those that haven't changed), you might invoke: $ cvs commit -r 3.0 Note that the number you specify with `-r' must be larger than any existing revision number. That is, if revision 3.0 exists, you cannot `cvs commit -r 1.3'. If you want to maintain several releases in parallel, you need to use a branch (*note Branching and merging::.). File: cvs.info, Node: Tags, Next: Sticky tags, Prev: Assigning revisions, Up: Revisions Tags-Symbolic revisions ======================= The revision numbers live a life of their own. They need not have anything at all to do with the release numbers of your software product. Depending on how you use CVS the revision numbers might change several times between two releases. As an example, some of the source files that make up RCS 5.6 have the following revision numbers: ci.c 5.21 co.c 5.9 ident.c 5.3 rcs.c 5.12 rcsbase.h 5.11 rcsdiff.c 5.10 rcsedit.c 5.11 rcsfcmp.c 5.9 rcsgen.c 5.10 rcslex.c 5.11 rcsmap.c 5.2 rcsutil.c 5.10 You can use the `tag' command to give a symbolic name to a certain revision of a file. You can use the `-v' flag to the `status' command to see all tags that a file has, and which revision numbers they represent. Tag names must start with an uppercase or lowercase letter and can contain uppercase and lowercase letters, digits, `-', and `_'. The two tag names `BASE' and `HEAD' are reserved for use by CVS. It is expected that future names which are special to CVS will be specially named, for example by starting with `.', rather than being named analogously to `BASE' and `HEAD', to avoid conflicts with actual tag names. You'll want to choose some convention for naming tags, based on information such as the name of the program and the version number of the release. For example, one might take the name of the program, immediately followed by the version number with `.' changed to `-', so that CVS 1.9 would be tagged with the name `cvs1-9'. If you choose a consistent convention, then you won't constantly be guessing whether a tag is `cvs-1-9' or `cvs1_9' or what. You might even want to consider enforcing your convention in the taginfo file (*note user-defined logging::.). The following example shows how you can add a tag to a file. The commands must be issued inside your working copy of the module. That is, you should issue the command in the directory where `backend.c' resides. $ cvs tag rel-0-4 backend.c T backend.c $ cvs status -v backend.c =================================================================== File: backend.c Status: Up-to-date Version: 1.4 Tue Dec 1 14:39:01 1992 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) Existing Tags: rel-0-4 (revision: 1.4) There is seldom reason to tag a file in isolation. A more common use is to tag all the files that constitute a module with the same tag at strategic points in the development life-cycle, such as when a release is made. $ cvs tag rel-1-0 . cvs tag: Tagging . T Makefile T backend.c T driver.c T frontend.c T parser.c (When you give CVS a directory as argument, it generally applies the operation to all the files in that directory, and (recursively), to any subdirectories that it may contain. *Note Recursive behavior::.) The `checkout' command has a flag, `-r', that lets you check out a certain revision of a module. This flag makes it easy to retrieve the sources that make up release 1.0 of the module `tc' at any time in the future: $ cvs checkout -r rel-1-0 tc This is useful, for instance, if someone claims that there is a bug in that release, but you cannot find the bug in the current working copy. You can also check out a module as it was at any given date. *Note checkout options::. When you tag more than one file with the same tag you can think about the tag as "a curve drawn through a matrix of filename vs. revision number." Say we have 5 files with the following revisions: file1 file2 file3 file4 file5 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 1.2*- 1.2 1.2 -1.2*- 1.3 \- 1.3*- 1.3 / 1.3 1.4 \ 1.4 / 1.4 \-1.5*- 1.5 1.6 At some time in the past, the `*' versions were tagged. You can think of the tag as a handle attached to the curve drawn through the tagged revisions. When you pull on the handle, you get all the tagged revisions. Another way to look at it is that you "sight" through a set of revisions that is "flat" along the tagged revisions, like this: file1 file2 file3 file4 file5 1.1 1.2 1.1 1.3 _ 1.1 1.2 1.4 1.1 / 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 1.3 1.6 1.3 \_ 1.4 1.4 1.5 File: cvs.info, Node: Sticky tags, Prev: Tags, Up: Revisions Sticky tags =========== Sometimes a working copy's revision has extra data associated with it, for example it might be on a branch (*note Branching and merging::.), or restricted to versions prior to a certain date by `checkout -D' or `update -D'. Because this data persists - that is, it applies to subsequent commands in the working copy - we refer to it as "sticky". Most of the time, stickiness is an obscure aspect of CVS that you don't need to think about. However, even if you don't want to use the feature, you may need to know *something* about sticky tags (for example, how to avoid them!). You can use the `status' command to see if any sticky tags or dates are set: $ cvs status driver.c =================================================================== File: driver.c Status: Up-to-date Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v Sticky Tag: rel-1-0-patches (branch: 1.7.2) Sticky Date: (none) Sticky Options: (none) The sticky tags will remain on your working files until you delete them with `cvs update -A'. The `-A' option retrieves the version of the file from the head of the trunk, and forgets any sticky tags, dates, or options. The most common use of sticky tags is to identify which branch one is working on, as described in *Note Accessing branches::. However, non-branch sticky tags have uses as well. For example, suppose that you want to avoid updating your working directory, to isolate yourself from possibly destabilizing changes other people are making. You can, of course, just refrain from running `cvs update'. But if you want to avoid updating only a portion of a larger tree, then sticky tags can help. If you check out a certain revision (such as 1.4) it will become sticky. Subsequent `cvs update' commands will not retrieve the latest revision until you reset the tag with `cvs update -A'. Likewise, use of the `-D' option to `update' or `checkout' sets a "sticky date", which, similarly, causes that date to be used for future retrievals. Many times you will want to retrieve an old version of a file without setting a sticky tag. The way to do that is with the `-p' option to `checkout' or `update', which sends the contents of the file to standard output. For example, suppose you have a file named `file1' which existed as revision 1.1, and you then removed it (thus adding a dead revision 1.2). Now suppose you want to add it again, with the same contents it had previously. Here is how to do it: $ cvs update -p -r 1.1 file1 >file1 =================================================================== Checking out file1 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v VERS: 1.1 *************** $ cvs add file1 cvs add: re-adding file file1 (in place of dead revision 1.2) cvs add: use 'cvs commit' to add this file permanently $ cvs commit -m test Checking in file1; /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 new revision: 1.3; previous revision: 1.2 done $ File: cvs.info, Node: Branching and merging, Next: Recursive behavior, Prev: Revisions, Up: Top Branching and merging ********************* CVS allows you to isolate changes onto a separate line of development, known as a "branch". When you change files on a branch, those changes do not appear on the main trunk or other branches. Later you can move changes from one branch to another branch (or the main trunk) by "merging". Merging involves first running `cvs update -j', to merge the changes into the working directory. You can then commit that revision, and thus effectively copy the changes onto another branch. * Menu: * Branches motivation:: What branches are good for * Creating a branch:: Creating a branch * Accessing branches:: Checking out and updating branches * Branches and revisions:: Branches are reflected in revision numbers * Magic branch numbers:: Magic branch numbers * Merging a branch:: Merging an entire branch * Merging more than once:: Merging from a branch several times * Merging two revisions:: Merging differences between two revisions * Merging adds and removals:: What if files are added or removed? File: cvs.info, Node: Branches motivation, Next: Creating a branch, Up: Branching and merging What branches are good for ========================== Suppose that release 1.0 of tc has been made. You are continuing to develop tc, planning to create release 1.1 in a couple of months. After a while your customers start to complain about a fatal bug. You check out release 1.0 (*note Tags::.) and find the bug (which turns out to have a trivial fix). However, the current revision of the sources are in a state of flux and are not expected to be stable for at least another month. There is no way to make a bugfix release based on the newest sources. The thing to do in a situation like this is to create a "branch" on the revision trees for all the files that make up release 1.0 of tc. You can then make modifications to the branch without disturbing the main trunk. When the modifications are finished you can elect to either incorporate them on the main trunk, or leave them on the branch.